Install Blog-Doc

Installing and using the app

Blog-Doc

A tiny blog and documentation SSG app.

Features

Functionalities ⚡

  • Paginated blog ↔️
  • Posts pagination ↔️
  • Write your content in Markdown 📝
  • Ability to use HTML in Markdown 🌟
  • Tag(s) for posts 🔖
  • Featured image for posts 🖼️
  • Links autogenerated at build time 🖇️
  • Archive route for posts 📦
  • Tags list route 🔖
  • Individual route for each tag 🏷️
  • Titles & Meta Descriptions 🤯
  • RSS feed 💐
  • Sitemap 🗺️
  • Search 🔍
  • Ids for H2 till H4 in Markdown #️⃣
  • Hot reloading in development mode 🔥

Solid stack of technologies 🪨

Backend (input)

  • Node.js 14.x or higher.
  • EJS is 100% JavaScript.
  • Markdown to focus on your content.

Frontend (output)

  • HTML, CSS and a tiny JS file.

Blazing fast and simple 🚀

  • A zero configuration static site generator.
  • Ready to use on your Node.js server as a Node.js app.
  • Ready to use, after build, as a static site.
  • Without any unnecessary functionalities, loads in a blink of an eye.
  • Easy to install and use.

Design 🎨

  • Responsive, elegant and simple layout.
  • Ready to use template for blog and/or documentation.
  • Easy to modify if you opt for another design.

How to install Blog-Doc ?

Blog-Doc is a Node.js app. You should have Node.js on your machine.
Always go for the LTS version. At the time of writing those lines it's 18.12.1 !

To install it, just head over it's Github repository and download it.
You can also download it's zip by clicking on the following link : Bloc-Doc ZIP.

Once everything is in place, extract the zipped files to a new folder and open it in your IDE (I use the one and only VS Code).
Then type in the terminal :

npm install

After the install, you'll see that Blog-Doc comes with some posts, a page and a template. Those files are located under the views folder in the pages, posts and templates folders. You can begin by removing those existing files and create your own Posts and Pages and also Templates.

To see what you content looks like, type in your terminal the following command :

npm run watch

This command will allow you to explore the app in the browser of your choice by visiting localhost on port 3000.

Generate a static site

How is it done ?!

When you try to reproduce an idea like an SSG, you learn a lot and especially to respect and appreciate the great and hard work of the developers who made applications used by thousand of people !

Rendering a static file out of a template is an easy task, but turning different routes working together to produce a Node.js app into some folders and a lot of files to generate a static site is not an easy one !

The file behind this trick in Blog-Doc is build.js. You can find this file under the functions folder. It's very similar to the filesRoute.js. The difference between the two is that filesRoute.js renders the posts, pages and templates in the Node.js app while build.js generates out of those posts, pages and templates a ready to use static site.

How does it work ?

To generate a static site out of your posts, pages and templates, type the following command in your terminal :

npm run build

This command will create a _site folder in which all the necessary folders and files are created. You can now copy the entire content of the _site folder to the server of your choice or just test it locally.

How to use it ?

Test it locally

Copy the content of the _site folder to a new folder and open it in your IDE, I use VS Code with the Live Server extension.
Launch the local server and you'll be able to explore the static site.

Host it !

Push the content of the _site folder to a host of your choice.
There are many free hosts for static sites. The most known are :

Nota Bene : the above list can be much longer with the different services out there to host a static site !

Deploy it to Deta !

You can deploy the content of the _site folder to Deta as a Node.js app !
It took me less than 5 minutes to do it !
Deta's documentation is great and straightforward !
You can take a look at the result by visiting Blog-Doc static with Express.
The implementation can be found on the following GitHub repository.

RSS !

⚠️ You MUST provide the live URL of your site in the settings.json file under the config folder before deploying the application.

At build time, a rss.xml file is generated in the _site folder.
This file takes the live URL that you provided to generate the correct links for your feed.
Nota Bene : the live URL MUST end with a slash / !

If you wish for browsers and software, that supports it, to automatically find your site's RSS feed, you can add a <link> tag in head.ejs just under the <title> tag like one of the following links :

<!-- head.ejs is located in the components folder under the views folder -->
<title>Blog-Doc | <%= titles.docTitle %></title>
<!-- If you intend to use Blog-Doc as a Node.js app use this example with `/rss` at the end -->
<link rel="alternate" type="application/rss+xml" title="Your site title" href="https://your-site.com/rss" />
<!-- If you intend to use the Blog-Doc as a static site use this one with `/rss.xml` at the end -->
<link rel="alternate" type="application/rss+xml" title="Your site title" href="https://your-site.com/rss.xml" />

Of course, you MUST edit rss.ejs in the layouts folder under the views folder.
You SHOULD replace the <title>, <description> and <copyright> tags with the ones of your site.
You MAY replace the <language> tag with the language of your site.
A list of available language codes can be found on the RSS language codes page.

Bellow is a screenshot of the RSS feed of Blog-Doc in Vivaldi browser

Sitemap

Like the RSS feed, you MUST provide the live URL of your site in the settings.json file under the config folder to generate the correct links for each page, post, tag and template as well as for the blog routes.

You can check the sitemap of your site under the /sitemap route.
At build time, a sitemap.xml is generated in the _site folder.

Search

Blog-Doc has a built-in search feature.
The search functionality allows a user to make a research on the titles and the contents of the posts.

You can check the search of your site under the /search route.
At build time, a posts.json and a search.js are generated in _site/js.
Also, at build time, a search.html is generated in the _site folder.

You can disable the search in the Node.js app as well as for the generated static site by giving searchFeature a value of false in the settings.json file under the config folder.

To see it in action, take a look at :

Ids for H2 till H4 in Markdown

Adding an id attribute to a heading tag, H2 till H4 only, is an optional activated feature by default.

This feature was built with edge cases and typing typos in mind :

  • Regex to match curly braces ignoring everything before the last hashtag
  • Replace accented characters, by their non accented letter
  • Replace upper case letters by lower case one
  • Remove special characters except hyphen and underscore
  • Replace any number of underscore by one hyphen
  • Replace any number of space by one hyphen
  • Remove any number of hyphen at the beginning
  • Replace any number of hyphen by one hyphen only
  • Remove any number of hyphen at the end

To add an id, add a curly braces with a hashtag followed by the id's text.
The following examples will give you a better idea :

<!-- Heading tags with an id property -->

## My awesome H2 title {# my-awesome-h2-title}

The HTML output will be : <h2 id="my-awesome-h2-title">My awesome H2 title</h2>

### My awesome H3 title {# my awesome h3 title}

The HTML output will be : <h3 id="my-awesome-h3-title">My awesome H3 title</h3>

#### My awesome H4 title {# My awesome H4 title}

The HTML output will be : <h4 id="my-awesome-h4-title">My awesome H4 title</h4>

Every Whitespace is automatically replaced by a hyphen and any number of consecutive hyphens are replaced by one hyphen only.
Any number of hyphen at the beginning or the end of the id's text are removed so the following is also valid :

## My awesome H2 title { # ----- My ----- aWEsOMe ----- h2 ----- tITlE ----- }

Whatever the number of whitespace characters / hyphens is at the beginning,
between the words or at the end, the HTML output will still be :

<h2 id="my-awesome-h2-title">My awesome H2 title</h2>

Anything before the last hashtag is ignored and special characters in the id's text are ignored too :

## My awesome H2 title { /!@# a comment ?%^& # -my= awesome+ h2 \ ( title ) | }

The HTML output will be : <h2 id="my-awesome-h2-title">My awesome H2 title</h2>

⚠️ Please be aware that the following special characters, if used inside the id's text after the last hashtag, will not be deleted :

& will be parsed to amp (ampersand)
" will be parsed to quot (quotation)
> will be parsed to gt (greater then)
< will be parsed to lt (less then)

As an example :

## Honey & Bees {#Honey & Bees}

The HTML output will be : <h2 id="honey-amp-bees">Honey & Bees</h2>

At build time, predefined ids will be generated into the HTML of the static site.

If you wish to disable this feature, set the addIdsToHeadings value to false in the settings.json file under the config folder.

What's next ?

I intend to make a lot of improvements to this app in my short free time.

You can take Blog-Doc as a prototype and modify it totally to use it with another design and/or another template language (I use the one and only plain JavaScript EJS).

I really hope that this app will be useful in any way for a lot of people out there, I'm considering it as my personal contribution to the Node.js, Express, EJS and Markdown communities.

Ideas, comments and suggestions are most welcome.

SYA, LebCit